home *** CD-ROM | disk | FTP | other *** search
/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d12 / debugtx.arc / 05COMMAN.DOC < prev    next >
Encoding:
Text File  |  1991-08-11  |  8.9 KB  |  190 lines
  1. CHAPTER 5   COMMAND LANGUAGE                                  5-1
  2.  
  3. In addition to immediate-execution assembly-language commands, 
  4. there is a set of commands recognized by the debugger.  They are 
  5. identified by the first keyword on the line being a single letter 
  6. (i.e., the second character of the line is a non-letter, usually 
  7. a comma or ENTER). 
  8.  
  9.  
  10. General Operands to Debugger Commands
  11.  
  12. Most of the debugger commands consist of their single-letter 
  13. identifier, followed by a comma, followed by one or more general 
  14. operands, separated by commas.  General operands can be one of 
  15. the following: 
  16.  
  17.    a. a numeric constant, whose format is just as in the assembly 
  18.       language (leading zero means default hex, otherwise default 
  19.       decimal) 
  20.    b. a register name
  21.    c. a user-symbol from the assembly-language program being 
  22.       debugged. 
  23.  
  24.  
  25. Format of Debugger Command Examples
  26.  
  27. Many of the examples given below will be given in double-quotes.  
  28. Note that the double-quotes are not part of the command.  You are 
  29. encouraged to try out the example on the debugger, by typing the 
  30. string within the quotes, not including the quotes, and always 
  31. followed by the ENTER key. Note further that the double-quoted 
  32. string may be broken across two lines of this manual, but that 
  33. does not mean you should type a ENTER where the string is broken-
  34. -debugger commands always consist of a single line, always 
  35. terminated by ENTER. 
  36.  
  37.  
  38. The Debugger Command Set
  39.  
  40. Following is a description of the debugger commands recognized:
  41.  
  42. B  sets and clears the fixed breakpoints of the program.  The 
  43.    debugger has four breakpoints.  Two are transitory; they are 
  44.    automatically cleared after each return from the program to 
  45.    the debugger.  They can be set by the G command. The other two 
  46.    are fixed-- they will remain in effect until you explicitly 
  47.    clear them.  The fixed breakpoints are controlled by this B 
  48.    command. 
  49.  
  50.    You follow the B with zero, one, or two general operands.  If 
  51.    there are zero operands (the B is followed immediately by a 
  52.    ENTER), then both fixed breakpoints are cleared.  If there are 
  53.    one or two operands, then the fixed breakpoints are set to the 
  54.    operands. 
  55.  
  56.    Note that previously-set breakpoints can be implicitly 
  57.    cleared, by overwriting them with other breakpoints.  If your 
  58.                                                              5-2
  59.  
  60.    B command has one operand, and there was one breakpoint 
  61.    previously set, the debugger sets the unused breakpoint, so 
  62.    that both remain in effect.  If your B command has one 
  63.    operand, and both breakpoints were previously set, the most 
  64.    recently-set breakpoint is saved, and the older breakpoint is 
  65.    overwritten. 
  66.  
  67.    The status screen, displayed by typing Ctrl-S, shows you the 
  68.    B-command breakpoints in effect.
  69.  
  70.    Examples: if you type "b,numout", the debugger will set a 
  71.    breakpoint at location NUMOUT, which should be a label in the 
  72.    program being debugged. You may start and stop the program 
  73.    many times, and the breakpoint will stay there.  You may even 
  74.    allow the program to stop at NUMOUT repeatedly; the breakpoint 
  75.    is not cleared even if the program stops there.  If you 
  76.    subsequently type the command "b,01000", then there will be 
  77.    breakpoints at both NUMOUT and location hex 01000.  If you 
  78.    then type "b,01200", the first breakpoint NUMOUT is 
  79.    overwritten; the two breakpoints now in effect are 01000 and 
  80.    01200.  The 01000 breakpoint will be next in line to be 
  81.    overwritten.  You may clear both breakpoints by typing "b".  
  82.    There is no way to clear one breakpoint at a time. 
  83.  
  84.  
  85. F  finds a string of memory bytes.  The memory to be searched 
  86.    starts at the current CS:IP location.  The string being 
  87.    sought contained in memory at the CS:IP location marked with 
  88.    the last Shift-F7 command.  The number of bytes in the target 
  89.    string is given as the first operand to the F command.  For 
  90.    example, "F,1" finds the next instance of a single byte value 
  91.    after the current CS;IP.  If the marked location points to a 
  92.    NOP, "F,1" will find the next NOP code.
  93.    
  94.    If you provide a second operand to F, it is a "retreat 
  95.    number".  For example, "F 2,10" assumes that you are looking 
  96.    for a 2-byte sequence, and you have retreated 10 bytes from 
  97.    the starting location for your search.  When the string is 
  98.    found, F will retreat 10 bytes from that string.  That way you 
  99.    can view the instructions that preceded the found string.  I 
  100.    use this feature when I am searching for BIOS and DOS 
  101.    interrupt calls in a program.  I want to retreat before the 
  102.    calls, to see what function numbers were loaded into 
  103.    registers.  I can use the F3 key to repeat the searches, 
  104.    giving me a sequence of disassembly displays with the 
  105.    interrupt in the middle. 
  106.    
  107.    F with no operands returns CS:IP to the marked location, in 
  108.    case you want to use F7 to deposit another string to be 
  109.    searched.
  110.    
  111.    If you have never pressed Shift-F7 in this session, the marked 
  112.    location is 0C000 of the program's starting segment.  That's 
  113.    often a good "scratchpad" area for small programs, far from 
  114.    both the program and the stack.  
  115.                                                              5-3
  116.  
  117. G  starts the user program.  You can give one or two operands to 
  118.    G, specifying locations within the program at which you wish 
  119.    to return to the debugger.  These are "transitory 
  120.    breakpoints"; they are cleared when the program returns to the 
  121.    debugger for any reason. 
  122.  
  123.    Whenever you start the program, at least one instruction from 
  124.    the program will be executed, even if there is a breakpoint at 
  125.    the current instruction pointer location.  This means you can 
  126.    set a breakpoint at the current location; instructing the 
  127.    program to return to the debugger the next time it gets back 
  128.    to the current location. 
  129.  
  130.  
  131. J  jumps to the location indicated by the operand, within the 
  132.    current code segment.  J is useful when you are exploring 
  133.    memory outside of your program's memory area.  In that case, 
  134.    the immediate JMP command is executed from a buffer within 
  135.    your program's original code segment.  JMP would therefore 
  136.    return you to that segment.  J will keep you in the distant 
  137.    segment. 
  138.  
  139.  
  140. O  sets a special fixed breakpoint.  Whenever your program calls 
  141.    MSDOS via INT 021, the debugger will monitor the function 
  142.    number passed in the AH register.  If the function number 
  143.    falls within the range specified by this command, the program 
  144.    will trap back to the debugger.  If you give two operands to 
  145.    O, the operands are the lower and upper bounds for the range 
  146.    of trapped functions.  If you give one operand, only that 
  147.    function-number will be trapped.  If you give no operands, any 
  148.    previous O-trap setting is cleared. 
  149.  
  150.    For example, note that function 3F hex is the READ function 
  151.    for MSDOS version 2.  If you want to trap whenever this READ 
  152.    function is invoked, you can issue the command O,03F and then 
  153.    start up your program with the G command.  Another example: 
  154.    suppose you want to insure that a program does not make any of 
  155.    the new Version 3 DOS calls, 59 hex and above.  You can issue 
  156.    the command O,059,0FF and then start your program. 
  157.  
  158.    NOTE: if the second operand is less than the first, then the 
  159.    range wraps around through zero.  For example, O,059,030 traps 
  160.    on 059 through 0FF, and also 0 through 030-- both version 3 
  161.    and version 1 calls. 
  162.  
  163.    SECOND NOTE: The EXIT function, hex 4C is always trapped by 
  164.    D86, regardless of your O-command settings.  The only way you 
  165.    should be able to exit from D86 is via the Q-command.  (If you 
  166.    do succeed in exiting some other way, I want to hear about it.  
  167.    In that case, D86 will become very confused if you reinvoke it 
  168.    before rebooting the computer.) 
  169.                                                              5-4
  170.  
  171. Q  exits the debugger and goes back to the operating system.
  172.  
  173.  
  174. W  writes the program (if it was a COM format) and the symbol 
  175.    table back to the disk.  In this present version, you don't 
  176.    have any options as to what to name the files.  The program 
  177.    name given when D86 was invoked is always used, except that 
  178.    the files are always written to the current directory.  The 
  179.    program file has the same extension as the file that was 
  180.    loaded, and the symbols file has the SYM extension.
  181.  
  182.    D86 writes the program from location 0100 in the original code 
  183.    segment, up to the end-of-file location saved when the program 
  184.    was loaded, and possibly extended by a patch-memory operation 
  185.    while at the end of the program.  Any symbols added while in 
  186.    the patch-memory mode are saved in the symbols file, so that 
  187.    you can "reverse engineer" programs for which you do not have 
  188.    source, and save the symbol-table results you have gleaned.
  189.  
  190.